<% if false # the license inside this if block assertains to this file -%>
# Copyright 2017 Google Inc.
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
<% end -%>

Google Cloud Platform for Puppet
--------------------------------

<%= lines(['[![Puppet Forge](',
           "http://img.shields.io/puppetforge/v/google/#{@api.prefix}.svg",
           ")](https://forge.puppetlabs.com/google/#{@api.prefix})"].join) -%>

This module installs all Google modules for Puppet to allow managing
[Google Cloud Platform][gcp] resources from your Puppet environment

#### Table of Contents

1. [Module Description](#module-description)
2. Setup
    * [Installing](#setup)
    * [Upgrading pre-release versions](#upgrading-pre_release-versions)
3. [Supported Google Cloud Platform Products][supported-products]
4. [Summary of Supported Products Types / Providers][supported-types]
5. [Supported Operating Systems](#supported-operating-systems)


## Module Description

This module is a convenience to install all Google Cloud Platform modules for
Puppet with a single command. You can install them individually if you wish as
well.


## Setup

To install this module on your Puppet Master (or Puppet Client/Agent), use the
Puppet module installer:

    puppet module install google/cloud

### Upgrading pre-release versions

If you already have pre-release modules installed (pre-release = modules with
version < 1.0.0) you need to force update of the modules, as they are
specifically strict about pre-release versions. You can do that by using the
`--force` argument on upgrade:

    puppet module upgrade --force google/cloud --version=<version>

You can find the latest version on [google/cloud][google-cloud-forge] Forge
page. If you omit the version you may get an intermedia upgrade, so please
re-run until you get the latest version.

Watch out for missing dependencies when you do that. If there are any missing
dependencies they will have a red `invalid` after the name of the module that
requires upgrade as well. The safest way is to upgrade all Google modules at
once (or remove them and do `puppet module install` again). Optionally you can
run a script to upgrade all Google modules, like this:

    puppet module list | awk '{print $2}' | grep '^google-' \
      | xargs -I{} puppet module upgrade --force {}

## Supported Google Cloud Platform Products

The `google/cloud` module installs the following modules automatically:

<%=
  lines(indent(products.keys.map do |p|
                 "- [#{p.name}](##{p.name.downcase.tr(' ', '-')})"
               end, 2))
-%>
  - [Google Authentication](#google-authentication)


## Summary of Supported Products Types / Providers

Below you can find a summary of each supported type and a brief description of
its intended behavior. For full details about each provider, properties,
parameters, usage and examples please visit its respective Puppet module project
page.

<% products.each do |product, config| -%>

### <%= product.name -%>

Detailed information can be found at the
[google-<%= product.prefix -%>][] project home page.
The list below is a summary of the supported types by the module:

<% product.objects.reject(&:exclude).each do |object| -%>

- `<%= object.out_name -%>`
<%= wrap_field(object.description, 2) -%>

<% end # objects.each -%>
<% unless config.bolt_tasks.nil? -%>

#### Bolt Tasks

<% config.bolt_tasks.each do |task| -%>

- `<%= task.target_file -%>`
<%= wrap_field(task.description_display, 2) -%>

<% end # config.bolt_tasks.each -%>

<% end # config.bolt_tasks.nil? -%>
<% end # products.each -%>

### Google Authentication

This module provides the types to authenticate with Google Cloud Platform.  When
executing operations on Google Cloud Platform, e.g. creating a virtual machine,
a SQL database, etc., you need to be authenticated to be able to carry on with
the request.  All Google Cloud Platform modules use an unified authentication
mechanism, provided by this module.

For examples, installation and usage visit the [google-gauth][] module home
page.


## Supported Operating Systems

<table>
  <tr><th>Product</th><th>Operating Systems</th></tr>
<% products.map do |product, config| -%>
<%   os_list = config.manifest.operating_systems -%>
  <tr>
    <td><%= product.name -%></td>
    <td>
<%= indent(os_list.map(&:all_versions).join("<br/>\n"), 6) %>
    </td>
  </tr>
<% end # products.map -%>
</table>


[supported-products]: #supported-google-cloud-platform-products
[supported-types]: #summary-of-supported-products-types--providers
<%=
  lines(products.map do |product, config|
          "[google-#{product.prefix}]: #{config.manifest.homepage}"
        end)
-%>
[google-gauth]: https://github.com/GoogleCloudPlatform/puppet-google-auth/blob/master/README.md
[gcp]: https://cloud.google.com
[google-cloud-forge]: https://forge.puppet.com/google/cloud
